[Back]

MacOS X Developer Preview 4 Release Notes Copyright © 2000 by Apple Computer, Inc. All Rights Reserved.

MacOS X Developer Preview 4 Release Notes:
Java APIs for Cocoa

The Java APIs for the core Cocoa frameworks rest upon the foundation of Apple's Java/Objective-C integration technology (also known as the "Java Bridge"). This technology allows you to access the full potential of the Cocoa frameworks using Java code and without having to write any Objective-C code. The bridge even allows you to subclass Objective-C objects in Java; in addition, using the bridging tools, you can wrap your own Objective-C code to make it accessible to Java applications.

Changes In MacOS X Developer Preview 4

The following new APIs added to AppKit and Foundation between DP3 and DP4 are not exported in the Java APIs. This is a bug and will be addressed for the next update:

• NSColor windowBackgroundColor
• NSAttributedString method readFromURL:options:documentAttributes: and supporting document type strings
• NSTableView methods
• The "contextInfo" argument in the new sheet APIs
• applicationShouldHandleReopen:hasVisibleWindows: NSApplication delegate method

All other new API has Java counterparts.

We intend to rename com.apple.yellow to com.apple.cocoa in the next update.

Changes In MacOS X Developer Preview 2

The Java VM was updated between DP1 and DP2. This was found to cause some incompatibilities:

• Non-public classes can no longer be instantiated in nib files when the nib file is loaded. (BlastApp's "RemainingHelicopters" class was not explicitly declared to be public, and the instance did not great created in the nib file under the new VM.)
• The compiler in DP1 was more forgiving in some areas; you might get errors from the Java compiler in DP2. (Java version of TextEdit had a compile problem due to lack of a cast.)
• The VSIZE (virtual memory size) of Cocoa Java apps is usually pretty large (> 100M) when viewed with ProcessManager or "ps", but most of this is virtual memory that is actually not committed and hence is not real unless your app explicitly uses a lot of memory.

Some of the APIs added between DP1 and DP2 do not yet appear in the Java frameworks. For example, the new tooltip methods on NSView and NSMatrix.

NSTypesetter, recently made public, is not available in the Java APIs.

Other Notes

• The packages for the Java APIs are currently named com.apple.yellow.application and com.apple.yellow.foundation. In addition, the same class and interface names are used in the Objective-C and Java APIs; thus the Objective-C prefixes are retained (NSApplication instead of Application, EOQualifier instead of Qualifier, etc). Note that the package names are likely to be changed to refer to "Cocoa" for the final release.

• Some Objective-C method names are overloaded to allow the default method-name mapping to work where applicable. For instance, replaceCharactersInRange:withAttributedString: and replaceCharactersInRange:withString: are now both represented as replaceCharactersInRange() in the Java APIs.

• In MacOS X Server DR1 (this is a while ago now), the Java APIs for the Application and Foundation frameworks were distributed in their alpha form. Since then package names and some method names have been changed. In case you have an app written against those APIs, there is a script to facilitate the conversion of application sources to their current form. The script does not provide complete coverage, but it will take care of most of the more straightforward cases, freeing you from some tedious conversion work. You can find the script and instructions on how to use it in /System/Developer/Java/Conversion/AlphaToYellow. Be sure to make a copy of your source directory before you apply the conversion, as the script works in place. Once you have run the scripts, trying to compile your program should pinpoint the remaining areas where conversion is still needed.

• Java does not provide a feature parallel to Objective-C's categories. The Cocoa Java APIs expose the functionality afforded by categories in Objective-C in several ways. One way is simply to fold the functionality into the base class: For instance, NSAttributedString methods provided in a category in the Application Kit are declared in Java in the base NSAttributedString class in Foundation. In other cases the methods are exposed in other, related classes: For instance, the NSBundle method loadNibNamed(), which is added by the Application Kit, is available in NSApplication in Java.

• Classes and methods which need to be public for some reason but which should be not considered a part of the public API are prefixed with an underbar. Thus, all classes and interfaces in com.apple.yellow.foundation._private should be considered private and not used in your applications. Similarly, com.apple.yellow.application._NSObsoleteMenuItemProtocol is also private and should not be used.

• Delegate and notification methods are declared using inner interfaces, for instance, NSWindow.Delegate and NSWindow.Notifications. Given that these methods are almost always optional, classes which act as delegates do not need to declare themselves to "implement" these interfaces. Data sources are declared similarly (for instance, NSTableView.DataSource). One difference with data sources is that the methods are not optional, and thus the data source should declare that it implements the interface.

• Most creation and initialization methods in the Cocoa classes are exposed as constructors in Java. Thus, instead of [NSView initWithFrame:rect], you use NSView(rect) to create views. This of course is the most natural way for Java, although sometimes the set of constructors might seem confusing. For instance, NSAttributedString provides the following constructors:

  NSAttributedString(String); (from a string)
  NSAttributedString(String, NSDictionary); (from a string and attributes)
  NSAttributedString(URL, NSMutableDictionary); (from the specified file, returning document properties)
  NSAttributedString(NSData, NSMutableDictionary); (from the specified file contents, returning document properties)
  NSAttributedString(NSFileWrapper, NSMutableDictionary); (from the specified file contents, returning document properties)
  NSAttributedString(NSData, URL, NSMutableDictionary); (from the specified HTML file contents and base URL, returning doc properties)

  In some cases, multiple initialization methods have been mapped to a single constructor in Java with multiple arguments; for instance, NSImage's initByReferencingFile: and initWithContentsOfFile: both map to NSImage(String, boolean), with the boolean indicating whether to reference (YES) or not (NO). Note that use of URLs to represent files also eliminates some of these cases.

  Finally, in other cases, static methods are used instead of constructors. This not only reduces the confusion associated with having many constructors, it also allows substitution of objects if necessary. NSColor is an example of this, with methods such as colorWithCalibratedRGB(), colorWithDeviceCMYK(), blackColor(), scrollBarColor(), and so on.

• Objects in C can be referenced weakly, that is, without an explicit retain. If an object is created in Java, and passed across the bridge into Objective-C, and it is not retained by anyone on the Objective-C side, the object's proxy will get released, causing the weak references on the Objective-C side to be invalidated, thereby causing invalid memory access. One way to work around this is to ensure that such objects are referenced strongly (that is, retained) in the Objective-C side; you can assure this by putting such objects into an NSArray. TextEdit does this with its Document objects.

• The APIs provide mutable versions of the classes representing the four structs used in Cocoa APIs (NSSize, NSPoint, NSRect, NSRange). The structs are mapped to the immutable or mutable counterparts on the Java side depending on the usage. If passed by value, the mapping is to the immutable version of the class. If passed by reference, with the purpose of getting a value back, the mapping is to the mutable version of the class. Finally, if passed by reference, but as an array, a custom mapping of the method is provided to convert the array appropriately to the Java side. New typedefs (NSRectPointer, NSRangeArray, and so on) were added to the Objective-C APIs to distinguish these two cases.

  Examples:

  -(NSDictionary)attributesAtIndex:(int)index effectiveRange:(NSRangePointer)range maps to
NSDictionary attributesAtIndex(int index, NSMutableRange range)

  void NSRectFillList(const NSRect *rects, int count) maps to
  void fillRectList(NSRect[] rects)

  Along the same lines, mutable versions of other classes (for example, NSDictionary) are used in APIs which pass these classes by reference in order to get a value back from the caller.

• To expose Objective-C APIs that take dictionaries which can contain the four basic structs (NSRect, NSPoint, NSSize, and NSRange) stored in NSValues, the setObjectForKey() method in NSDictionary in Java checks to see whether the object is a instance of a class corresponding to these structs. These are converted to an NSValue before being stored in the dictionary. In addition objectForKey() performs the reverse mapping. This allows the storage of these kinds of values in NSDictionaries to happen naturally from both Java and Objective-C. Note that the NSNumber to Number conversion already happens in all cases.

  Examples of this include NSScreen's deviceDescription(), which returns a dictionary, and NSAttributedString's RTFFromRange(), which takes a dictionary as an argument.

  Two limitations of this feature are:

  1. The appropriate NSValue constructor should be used on the Objective-C side to put the structs in NSValues (valueWithRect: instead of valueWithBytes:objCType:); otherwise the automatic conversion won't take place.
     
  2. The conversion is implemented in NSDictionary only and not in the other collection classes.
     

• NSStringReference and NSMutableStringReference allow the efficient representation of strings stored on the Objective-C side. These classes basically provide a way to wrap the NSString and NSMutableString classes rather than morph them to Java's String. In addition, they provide some functionality not available in Java's String and StringBuffer classes.

  Note that in general morphing is the right thing to do: You want to communicate strings in Java using Java's built-in java.lang.String class. Like NSString, this class stores a string of Unicode characters and provides API to deal with them. Thus most of the Cocoa API in Java still takes or returns String, which is automatically converted to and from an NSString.

• The graphics functions in the Application Kit are exposed as static methods in the class NSGraphics.

• Java's URL class is used as a means to refer to files in some APIs. For example, NSImage provides the constructor NSImage(URL) in addition to the constructors taking file name as a String. Similarly, you can use the NSOpenPanel method URLs() to get back an array of URLs that represent the files selected by the user. Although these methods currently work only with URLs representing local files, they will soon work with other types of URLs. In addition, additional APIs that take or return URLs will be added throughout the frameworks where appropriate.

• Some classes in Foundation are not exposed mainly because the same functionality is provided in the native Java APIs. Examples include NSFileManager, NSFileHandle, NSTask, NSThread, NSValue, and NSScanner.

• The Objective-C NSCalendarDate class is NSGregorianDate on the Java side. (It doesn't morph; the name just changes.)

• Additional utility methods on NSPathUtilities (fileAttributes(), setFileAttributes(), pathFromURL(), URLWithPath(), and searchPathForDirectoriesInDomains()) cover functionality available in Objective-C through functions or unexposed classes.

• Use NSPropertyListSerialization to read and write the property list classes (NSData, NSString, NSDictionary, and NSArray).

• NSAutoreleasePool methods push() and pop() are exposed in Java. They should rarely be needed.

• NSDecimalNumber is morphed to BigNumber in Java.

• In the /System/Developer/Examples/Java/AppKit directory you can find the sources to several complete applications written in Java using the Cocoa APIs:
  • TextEdit is a text editor built on the Cocoa text system. (Objective-C source for TextEdit are also provided, allowing you to compare the two source bases.)
  • Sketch is a drawing application which also shows off scripting features of Cocoa. (Objective-C sources for Sketch are also provided.)
  • BlastApp is a simple shoot-em-up game.

• You can use JavaBrowser (also in the /System/Developer/Applications directory) to look at the classes and interfaces provided in Java packages available on the system.